<!--
  * t
  ****************************************************************************
  * Copyright 2018-2023,2024 Thomas E. Dickey                                *
  * Copyright 1998-2016,2017 Free Software Foundation, Inc.                  *
  *                                                                          *
  * Permission is hereby granted, free of charge, to any person obtaining a  *
  * copy of this software and associated documentation files (the            *
  * "Software"), to deal in the Software without restriction, including      *
  * without limitation the rights to use, copy, modify, merge, publish,      *
  * distribute, distribute with modifications, sublicense, and/or sell       *
  * copies of the Software, and to permit persons to whom the Software is    *
  * furnished to do so, subject to the following conditions:                 *
  *                                                                          *
  * The above copyright notice and this permission notice shall be included  *
  * in all copies or substantial portions of the Software.                   *
  *                                                                          *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  *                                                                          *
  * Except as contained in this notice, the name(s) of the above copyright   *
  * holders shall not be used in advertising or otherwise to promote the     *
  * sale, use or other dealings in this Software without prior written       *
  * authorization.                                                           *
  ****************************************************************************
  * @Id: curs_terminfo.3x,v 1.136 2024/04/14 00:14:40 tom Exp @
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
<TITLE>curs_terminfo 3x 2024-04-13 ncurses 6.5 Library calls</TITLE>
<link rel="author" href="mailto:bug-ncurses@gnu.org">

</HEAD>
<BODY>
<H1 class="no-header">curs_terminfo 3x 2024-04-13 ncurses 6.5 Library calls</H1>
<PRE>
<STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>                Library calls               <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>




</PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
       <STRONG>del_curterm</STRONG>,   <STRONG>mvcur</STRONG>,   <STRONG>putp</STRONG>,   <STRONG>restartterm</STRONG>,   <STRONG>set_curterm</STRONG>,  <STRONG>setupterm</STRONG>,
       <STRONG>tigetflag</STRONG>,  <STRONG>tigetnum</STRONG>,  <STRONG>tigetstr</STRONG>,  <STRONG>tiparm</STRONG>,  <STRONG>tiparm_s</STRONG>,  <STRONG>tiscan_s</STRONG>,  <STRONG>tparm</STRONG>,
       <STRONG>tputs</STRONG>,  <STRONG>vid_attr</STRONG>,  <STRONG>vid_puts</STRONG>,  <STRONG>vidattr</STRONG>,  <STRONG>vidputs</STRONG>  - <EM>curses</EM> interfaces to
       <EM>terminfo</EM> database


</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
       <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
       <STRONG>#include</STRONG> <STRONG>&lt;term.h&gt;</STRONG>

       <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG>

       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolnames[];</STRONG>
       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolcodes[];</STRONG>
       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolfnames[];</STRONG>
       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numnames[];</STRONG>
       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numcodes[];</STRONG>
       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>numfnames[];</STRONG>
       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strnames[];</STRONG>
       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strcodes[];</STRONG>
       <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG>

       <STRONG>int</STRONG> <STRONG>setupterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>
       <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG>

       <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG>
            <EM>/*</EM> <EM>or</EM> <EM>*/</EM>
       <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> ... <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
       <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
       <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>vid_puts(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG>
       <STRONG>int</STRONG> <STRONG>vid_attr(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newcol</EM><STRONG>);</STRONG>

       <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG>
       <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG>
       <STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG>

       <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG>

       <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM>
       <STRONG>char</STRONG> <STRONG>*tiparm_s(int</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG>
       <STRONG>int</STRONG> <STRONG>tiscan_s(int</STRONG> <STRONG>*</STRONG><EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG>

       <EM>/*</EM> <EM>deprecated</EM> <EM>*/</EM>
       <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG>


</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
       These low-level functions must be called by programs that deal directly
       with  the  <EM>terminfo</EM>  database  to handle certain terminal capabilities,
       such as programming function keys.  For all other functionality, <EM>curses</EM>
       functions are more suitable and their use is recommended.

       None  of  these  functions  use  (or  are aware of) multibyte character
       strings such as UTF-8.

       <STRONG>o</STRONG>   Capability names and codes use the POSIX portable character set.

       <STRONG>o</STRONG>   Capability string values have  no  associated  encoding;  they  are
           strings of 8-bit characters.


</PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE>
       Initially, <STRONG>setupterm</STRONG> should be called.  The high-level <EM>curses</EM> functions
       <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level  set  of
       terminal-dependent variables listed in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>.

       Applications  can  use  the  terminal capabilities either directly (via
       header  definitions),  or  by  special  functions.   The  header  files
       <EM>curses.h</EM>  and  <EM>term.h</EM>  should  be  included  (in that order) to get the
       definitions for these strings, numbers, and flags.

       The <EM>terminfo</EM> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized  by  <STRONG>setupterm</STRONG>
       as follows.

       <STRONG>o</STRONG>   If  <STRONG>use_env(FALSE)</STRONG>  has  been  called, values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG>
           specified in <EM>terminfo</EM> are used.

       <STRONG>o</STRONG>   Otherwise, if the environment variables <EM>LINES</EM>  and  <EM>COLUMNS</EM>  exist,
           their values are used.  If these environment variables do not exist
           and the program is running in a window, the current window size  is
           used.   Otherwise,  if  the environment variables do not exist, the
           values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <EM>terminfo</EM> database are
           used.

       Parameterized  strings  should  be  passed through <STRONG>tparm</STRONG> to instantiate
       them.  All <EM>terminfo</EM> strings (including the output of <STRONG>tparm</STRONG>)  should  be
       sent  to the terminal device with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>.  Call <STRONG>reset_shell_mode</STRONG>
       to restore the terminal modes before exiting; see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>.

       Programs that use cursor addressing should

       <STRONG>o</STRONG>   output <STRONG>enter_ca_mode</STRONG> upon startup and

       <STRONG>o</STRONG>   output <STRONG>exit_ca_mode</STRONG> before exiting.

       Programs that execute shell subprocesses should

       <STRONG>o</STRONG>   call <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before the  shell  is
           called and

       <STRONG>o</STRONG>   output  <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning from
           the shell.

       <STRONG>setupterm</STRONG> reads in the <EM>terminfo</EM>  database,  initializing  the  <EM>terminfo</EM>
       structures,  but  does  not set up the output virtualization structures
       used by <EM>curses</EM>.  Its parameters follow.

          <EM>term</EM> is the terminal type, a character string.  If <EM>term</EM> is null, the
               environment variable <EM>TERM</EM> is read.

          <EM>filedes</EM>
               is  the  file  descriptor used for getting and setting terminal
               I/O modes.

               Higher-level applications use  <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>  to  initialize  the
               terminal,  passing  an  output <EM>stream</EM> rather than a <EM>descriptor</EM>.
               In  <EM>curses</EM>,  the  two  are  the  same  because  <STRONG>newterm</STRONG>   calls
               <STRONG>setupterm</STRONG>,  passing the file descriptor derived from its output
               stream parameter.

          <EM>errret</EM>
               points to an optional location where an  error  status  can  be
               returned  to the caller.  If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG>
               returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a  status  value  in  the  integer
               pointed  to  by  <EM>errret</EM>.   A  return  value of <STRONG>OK</STRONG> combined with
               status of <STRONG>1</STRONG> in <EM>errret</EM> is normal.

               If <STRONG>ERR</STRONG> is returned, examine <EM>errret:</EM>

               <STRONG>1</STRONG>    means that the terminal is hardcopy, and  cannot  be  used
                    for <EM>curses</EM> applications.

                    <STRONG>setupterm</STRONG>  determines  if  the entry is a hardcopy type by
                    checking the <STRONG>hardcopy</STRONG> (<STRONG>hc</STRONG>) capability.

               <STRONG>0</STRONG>    means that the terminal could not be found, or that it  is
                    a  generic  type, having too little information for <EM>curses</EM>
                    applications to run.

                    <STRONG>setupterm</STRONG> determines if the entry is  a  generic  type  by
                    checking the <STRONG>generic_type</STRONG> (<STRONG>gn</STRONG>) capability.

               <STRONG>-1</STRONG>   means that the <EM>terminfo</EM> database could not be found.

               If  <EM>errret</EM>  is  null,  <STRONG>setupterm</STRONG>  reports an error message upon
               finding an error and exits.  Thus, the simplest call is:

                      setupterm((char *)0, 1, (int *)0);

               which uses all the defaults and sends the output to <STRONG>stdout</STRONG>.


</PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE>
       <STRONG>setupterm</STRONG> stores its information  about  the  terminal  in  a  <EM>TERMINAL</EM>
       structure pointed to by the global variable <STRONG>cur_term</STRONG>.  If it detects an
       error,  or  decides  that  the  terminal  is  unsuitable  (hardcopy  or
       generic),  it  discards  this  information,  making it not available to
       applications.

       If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type,  it  will
       reuse  the  information.   It  maintains  only  one  copy  of  a  given
       terminal's capabilities in memory.   If  it  is  called  for  different
       terminal  types,  <STRONG>setupterm</STRONG>  allocates  new  storage  for  each  set of
       terminal capabilities.

       <STRONG>set_curterm</STRONG> sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>,  and  makes  all  of  the  <EM>terminfo</EM>
       Boolean,  numeric,  and string variables use the values from <EM>nterm</EM>.  It
       returns the old value of <STRONG>cur_term</STRONG>.

       <STRONG>del_curterm</STRONG> frees the space pointed to by <EM>oterm</EM> and makes it  available
       for  further  use.  If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>, references to any
       of the <EM>terminfo</EM> Boolean, numeric, and string variables  thereafter  may
       refer  to  invalid  memory  locations  until another <STRONG>setupterm</STRONG> has been
       called.

       <STRONG>restartterm</STRONG> is similar to <STRONG>setupterm</STRONG> and  <STRONG>initscr</STRONG>,  except  that  it  is
       called  after  restoring  memory to a previous state (for example, when
       reloading a game saved as a core image dump).  <STRONG>restartterm</STRONG> assumes that
       the  windows  and  the  input  and  output options are the same as when
       memory was saved, but the terminal type and baud rate may be different.
       Accordingly,  <STRONG>restartterm</STRONG>  saves  various  terminal  state  bits, calls
       <STRONG>setupterm</STRONG>, and then restores the bits.


</PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE>
       <STRONG>tparm</STRONG> instantiates the string <EM>str</EM> with parameters  <EM>pi</EM>.   A  pointer  is
       returned to the result of <EM>str</EM> with the parameters applied.  Application
       developers should keep in mind these quirks of the interface:

       <STRONG>o</STRONG>   Although <STRONG>tparm</STRONG>'s actual parameters may be integers or strings,  the
           prototype expects <EM>long</EM> (integer) values.

       <STRONG>o</STRONG>   Aside  from  the  <STRONG>set_attributes</STRONG>  (<STRONG>sgr</STRONG>)  capability,  most terminal
           capabilities require no more than one or two parameters.

       <STRONG>o</STRONG>   Padding information is ignored  by  <STRONG>tparm</STRONG>;  it  is  interpreted  by
           <STRONG>tputs</STRONG>.

       <STRONG>o</STRONG>   The  capability  string  is  null-terminated.   Use "\200" where an
           ASCII NUL is needed in the output.

       <STRONG>tiparm</STRONG> is a newer form of <STRONG>tparm</STRONG>  which  uses  <EM>stdarg.h</EM>  rather  than  a
       fixed-parameter  list.   Its  numeric  parameters  are <EM>int</EM>s rather than
       <EM>long</EM>s.

       Both <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> assume that  the  application  passes  parameters
       consistent  with the terminal description.  Two extensions are provided
       as alternatives to deal with untrusted data.

       <STRONG>o</STRONG>   <STRONG>tiparm_s</STRONG> is an extension which is a safer formatting function  than
           <STRONG>tparm</STRONG> or <STRONG>tiparm</STRONG>, because it allows the developer to tell the <EM>curses</EM>
           library how many parameters to expect in the  parameter  list,  and
           which may be string parameters.

           The  <EM>mask</EM>  parameter has one bit set for each of the parameters (up
           to 9) passed as <EM>char</EM> pointers rather than numbers.

       <STRONG>o</STRONG>   The  extension  <STRONG>tiscan_s</STRONG>  allows  the  application  to  inspect   a
           formatting capability to see what the <EM>curses</EM> library would assume.


</PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE>
       String  capabilities  can  contain  padding  information,  a time delay
       (accommodating performance limitations of hardware terminals) expressed
       as <STRONG>$&lt;</STRONG><EM>n</EM><STRONG>&gt;</STRONG>, where <EM>n</EM> is a nonnegative integral count of milliseconds.  If <EM>n</EM>
       exceeds 30,000 (thirty seconds), it is capped at that value.

       <STRONG>tputs</STRONG> interprets time-delay information in the string <EM>str</EM>  and  outputs
       it, executing the delays:

       <STRONG>o</STRONG>   The  <EM>str</EM> parameter must be a <EM>terminfo</EM> string variable or the return
           value of <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>.

           The <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM>  interface,
           which happens to share these function names with the <EM>terminfo</EM> API.

       <STRONG>o</STRONG>   <EM>affcnt</EM> is the number of lines affected, or <STRONG>1</STRONG> if not applicable.

       <STRONG>o</STRONG>   <EM>putc</EM> is a <EM>putchar</EM>-like function to which the characters are passed,
           one at a time.

           If <STRONG>tputs</STRONG> processes  a  time-delay,  it  uses  the  <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG>
           function,  routing  any  resulting  padding characters through this
           function.

       <STRONG>putp</STRONG> calls "<STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>".  The output of <STRONG>putp</STRONG> always goes to
       <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>.

       <STRONG>vidputs</STRONG> displays the string on the terminal in the video attribute mode
       <EM>attrs</EM>, which is any combination of the attributes listed in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>.
       The characters are passed to the <EM>putchar</EM>-like function <EM>putc</EM>.

       <STRONG>vidattr</STRONG> is like <STRONG>vidputs</STRONG>, except that it outputs through <STRONG>putchar(3)</STRONG>.

       <STRONG>vid_attr</STRONG>  and <STRONG>vid_puts</STRONG> correspond to <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG>, respectively.
       They use multiple parameters to represent the character attributes  and
       color; namely,

       <STRONG>o</STRONG>   <EM>attrs</EM>, of type <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, for the attributes and

       <STRONG>o</STRONG>   <EM>pair</EM>, of type <EM>short</EM>, for the color pair number.

       Use  the  attribute  constants  prefixed  with  "<STRONG>WA_</STRONG>" with <STRONG>vid_attr</STRONG> and
       <STRONG>vid_puts</STRONG>.

       X/Open Curses reserves the <EM>opts</EM> argument for future  use,  saying  that
       applications  must  provide  a  null pointer for that argument; but see
       section "EXTENSIONS" below.

       <STRONG>mvcur</STRONG> provides low-level cursor motion.  It  takes  effect  immediately
       (rather  than  at the next refresh).  Unlike the other low-level output
       functions, which either write to the standard output or pass an  output
       function  parameter,  <STRONG>mvcur</STRONG> uses an output file descriptor derived from
       the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>.

       While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions that do not use high-level
       <EM>curses</EM>  state,  <EM>ncurses</EM>  declares them in <EM>curses.h</EM> because System V did
       this (see section "HISTORY" below).


</PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE>
       <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, and <STRONG>tigetstr</STRONG> return the value  of  the  capability
       corresponding  to  the <EM>terminfo</EM> <EM>cap-code</EM>, such as <STRONG>xenl</STRONG>, passed to them.
       The <EM>cap-code</EM> for each capability is given in the table column  entitled
       <EM>cap-code</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.

       These functions return special values to denote errors.

       <STRONG>tigetflag</STRONG> returns

       <STRONG>-1</STRONG>     if <EM>cap-code</EM> is not a Boolean capability, or

       <STRONG>0</STRONG>      if it is canceled or absent from the terminal description.

       <STRONG>tigetnum</STRONG> returns

       <STRONG>-2</STRONG>     if <EM>cap-code</EM> is not a numeric capability, or

       <STRONG>-1</STRONG>     if it is canceled or absent from the terminal description.

       <STRONG>tigetstr</STRONG> returns

       <STRONG>(char</STRONG> <STRONG>*)-1</STRONG>
              if <EM>cap-code</EM> is not a string capability, or

       <STRONG>0</STRONG>      if it is canceled or absent from the terminal description.


</PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE>
       These null-terminated arrays contain

       <STRONG>o</STRONG>   the short <EM>terminfo</EM> names ("codes"),

       <STRONG>o</STRONG>   the <EM>termcap</EM> names ("names"), and

       <STRONG>o</STRONG>   the long <EM>terminfo</EM> names ("fnames")

       for each of the predefined <EM>terminfo</EM> variables:

              <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG>
              <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG>
              <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*strnames[]</STRONG>, <STRONG>*strcodes[]</STRONG>, <STRONG>*strfnames[]</STRONG>


</PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE>
       Each successful call to <STRONG>setupterm</STRONG> allocates memory to hold the terminal
       description.  As a side effect, it  sets  <STRONG>cur_term</STRONG>  to  point  to  this
       memory.  If an application calls

              del_curterm(cur_term);

       the memory will be freed.

       The  formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage allocated
       by <STRONG>setupterm</STRONG> as follows.

       <STRONG>o</STRONG>   They add the "static" <EM>terminfo</EM>  variables  [a-z].   Before  <EM>ncurses</EM>
           6.3, those were shared by all screens.  With <EM>ncurses</EM> 6.3, those are
           allocated per screen.  See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>.

       <STRONG>o</STRONG>   To improve performance, <EM>ncurses</EM> 6.3 caches the result of  analyzing
           <EM>terminfo</EM>  strings  for  their parameter types.  That is stored as a
           binary tree referenced from the <EM>TERMINAL</EM> structure.

       The higher-level <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> functions use <STRONG>setupterm</STRONG>.  Normally
       they  do  not free this memory, but it is possible to do that using the
       <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG> function.


</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
       X/Open Curses defines no failure conditions.  In <EM>ncurses</EM>,

       <STRONG>del_curtem</STRONG>
            fails if its terminal parameter is null.

       <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error codes.

       <STRONG>restartterm</STRONG>
            fails if the associated call to <STRONG>setupterm</STRONG> returns an error.

       <STRONG>setupterm</STRONG>
            fails if it cannot allocate enough memory, or create  the  initial
            windows  (<STRONG>stdscr</STRONG>,  <STRONG>curscr</STRONG>,  and <STRONG>newscr</STRONG>) Other error conditions are
            documented above.

       <STRONG>tparm</STRONG>
            returns a null pointer if the capability would require  unexpected
            parameters;  that  is,  too  many,  too  few,  or  incorrect types
            (strings where integers are expected, or vice versa).

       <STRONG>tputs</STRONG>
            fails if the string parameter is null.  It  does  not  detect  I/O
            errors:  X/Open  Curses states that <STRONG>tputs</STRONG> ignores the return value
            of the output function <EM>putc</EM>.


</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
       The <STRONG>vid_attr</STRONG> function in <EM>ncurses</EM> is a special case.  It was  originally
       implemented based on a draft of X/Open Curses, as a macro, before other
       parts of the <EM>ncurses</EM> wide-character API were developed, and unlike  the
       other  wide-character  functions,  is  also  provided  in the non-wide-
       character configuration.


</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE>
       The functions marked as extensions were designed for <EM>ncurses</EM>,  and  are
       not  found  in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM>
       implementation.

       <EM>ncurses</EM> allows <EM>opts</EM> to be a pointer to <EM>int</EM>, which  overrides  the  <EM>pair</EM>
       (<EM>short</EM>) argument.


</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
       <STRONG>setterm</STRONG> is not described by X/Open and must be considered non-portable.
       All other functions are as described by X/Open.


</PRE><H3><a name="h3-Compatibility-Macros">Compatibility Macros</a></H3><PRE>
       This implementation  provides  a  few  macros  for  compatibility  with
       systems  before  SVr4  (see  section  "HISTORY"  below).   They include
       <STRONG>Bcrmode</STRONG>, <STRONG>Bfixterm</STRONG>, <STRONG>Bgettmode</STRONG>,  <STRONG>Bnocrmode</STRONG>,  <STRONG>Bresetterm</STRONG>,  <STRONG>Bsaveterm</STRONG>,  and
       <STRONG>Bsetterm</STRONG>.

       In  SVr4,  these  are  found  in  <EM>curses.h</EM>, but except for <STRONG>setterm</STRONG>, are
       likewise macros.  The one function, <STRONG>setterm</STRONG>, is mentioned in the manual
       page.  It further notes that <STRONG>setterm</STRONG> was replaced by <STRONG>setupterm</STRONG>, stating
       that the call
              setupterm(<EM>term</EM>, 1, (int *)0)
       provides the same  functionality  as  <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>,  discouraging  the
       latter  for  new programs.  <EM>ncurses</EM> implements each of these symbols as
       macros for BSD <EM>curses</EM> compatibility.


</PRE><H3><a name="h3-Legacy-Data">Legacy Data</a></H3><PRE>
       <STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>.  This  is  not
       part of X/Open Curses, but is assumed by some applications.

       Other  implementions  may not declare the capability name arrays.  Some
       provide them without declaring them.  X/Open Curses  does  not  specify
       them.

       Extended  terminal  capability  names,  as defined by "<STRONG>tic</STRONG> <STRONG>-x</STRONG>", are not
       stored in the arrays described here.


</PRE><H3><a name="h3-Output-Buffering">Output Buffering</a></H3><PRE>
       Older versions of <EM>ncurses</EM> assumed that the file  descriptor  passed  to
       <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to
       the corresponding stream.  In  addition  to  the  limitation  that  the
       terminal  was  left  in  block-buffered  mode  on  exit  (like System V
       <EM>curses</EM>), it was problematic because <EM>ncurses</EM> did not  allow  a  reliable
       way to clean up on receiving <STRONG>SIGTSTP</STRONG>.

       The  current version (ncurses6) uses output buffers managed directly by
       <EM>ncurses</EM>.  Some of the low-level functions described in this manual page
       write  to  the  standard  output.  They are not signal-safe.  The high-
       level functions in <EM>ncurses</EM> employ alternate versions of these functions
       using the more reliable buffering scheme.


</PRE><H3><a name="h3-Function-Prototypes">Function Prototypes</a></H3><PRE>
       The  X/Open  Curses  prototypes  are  based  on  the SVr4 <EM>curses</EM> header
       declarations, which were defined at the same time the  C  language  was
       first standardized in the late 1980s.

       <STRONG>o</STRONG>   X/Open  Curses  uses  <EM>const</EM>  less  effectively  than a later design
           might, sometimes applying it needlessly to values that are  already
           constant,  and  in  most cases overlooking parameters that normally
           would use <EM>const</EM>.  Passing <EM>const</EM>-qualified parameters  to  functions
           that  do  not  declare  them  <EM>const</EM>  may  prevent  the program from
           compiling.   On  the  other  hand,  "writable   strings"   are   an
           obsolescent feature.

           As  an  extension,  this implementation can be configured to change
           the function prototypes to use the <EM>const</EM> keyword.  The <EM>ncurses</EM>  ABI
           6 enables this feature by default.

       <STRONG>o</STRONG>   X/Open  Curses  prototypes <STRONG>tparm</STRONG> with a fixed number of parameters,
           rather than a variable argument list.

           This implementation uses a  variable  argument  list,  but  can  be
           configured  to use the fixed-parameter list.  Portable applications
           should provide nine parameters after the format;  zeroes  are  fine
           for this purpose.

           In  response  to review comments by Thomas E. Dickey, X/Open Curses
           Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009.

           While <STRONG>tiparm</STRONG> is always provided in <EM>ncurses</EM>, the older form is  only
           available  as  a build-time configuration option.  If not specially
           configured, <STRONG>tparm</STRONG> is the same as <STRONG>tiparm</STRONG>.

       Both forms of <STRONG>tparm</STRONG> have drawbacks:

       <STRONG>o</STRONG>   Most of the calls to <STRONG>tparm</STRONG> use only one or two parameters.  Passing
           nine on each call is awkward.

           Using  <EM>long</EM>  for the numeric parameter type is a workaround to make
           the parameter use the same amount of  stack  as  a  pointer.   That
           approach  dates  back  to the mid-1980s, before C was standardized.
           Since then, there is a standard (and pointers are not  required  to
           fit in a <EM>long</EM>).

       <STRONG>o</STRONG>   Providing  the  right  number of parameters for a variadic function
           such  as  <STRONG>tiparm</STRONG>  can  be  a  problem,  in  particular  for  string
           parameters.   However,  only a few <EM>terminfo</EM> capabilities use string
           parameters (for instance, the ones used for  programmable  function
           keys).

           The <EM>ncurses</EM> library checks usage of these capabilities, and returns
           an error if the capability mishandles string  parameters.   But  it
           cannot  check  if  a  calling program provides strings in the right
           places for the <STRONG>tparm</STRONG> calls.

           The <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> program checks its use of  these  capabilities  with  a
           table, so that it calls <STRONG>tparm</STRONG> correctly.

   <STRONG>Special</STRONG> <EM>TERM</EM> <STRONG>treatment</STRONG>
       If configured to use the terminal driver, as with the MinGW port,

       <STRONG>o</STRONG>   <STRONG>setupterm</STRONG>  interprets  a missing/empty <EM>TERM</EM> variable as the special
           value "unknown".

           SVr4 <EM>curses</EM> uses the special value "dumb".

           The difference  between  the  two  is  that  the  former  uses  the
           <STRONG>generic_type</STRONG>  (<STRONG>gn</STRONG>)  <EM>terminfo</EM> capability, while the latter does not.
           A generic terminal is unsuitable for full-screen applications.

       <STRONG>o</STRONG>   <STRONG>setupterm</STRONG> allows explicit use of the the windows console driver  by
           checking  if <STRONG>$TERM</STRONG> is set to "#win32con" or an abbreviation of that
           string.


</PRE><H3><a name="h3-Other-Portability-Issues">Other Portability Issues</a></H3><PRE>
       In SVr4, <STRONG>set_curterm</STRONG> returns an <EM>int</EM>, <STRONG>OK</STRONG> or  <STRONG>ERR</STRONG>.   We  have  chosen  to
       implement the X/Open Curses semantics.

       In SVr4, the third argument of <STRONG>tputs</STRONG> has the type "<STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>".

       At  least one implementation of X/Open Curses (Solaris) returns a value
       other than <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>.  It instead returns the length of  the
       string, and does no error checking.

       X/Open  Curses notes that after calling <STRONG>mvcur</STRONG>, the <EM>curses</EM> state may not
       match the actual terminal state, and that an application  should  touch
       and  refresh  the  window  before  resuming  normal <EM>curses</EM> calls.  Both
       <EM>ncurses</EM> and SVr4 <EM>curses</EM> implement <STRONG>mvcur</STRONG> using the <EM>SCREEN</EM> data allocated
       in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>.  So though it is documented as a <EM>terminfo</EM>
       function, <STRONG>mvcur</STRONG> is really a <EM>curses</EM> function that is not well specified.

       X/Open Curses states that the old location must be given for  <STRONG>mvcur</STRONG>  to
       accommodate  terminals  that lack absolute cursor positioning.  <EM>ncurses</EM>
       allows the caller to use -1 for either or both old coordinates.  The -1
       tells  <EM>ncurses</EM>  that  the old location is unknown, and that it must use
       only absolute motion, as  with  the  <STRONG>cursor_address</STRONG>  (<STRONG>cup</STRONG>)  capability,
       rather  than  the  least  costly  combination  of absolute and relative
       motion.


</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE>
       SVr2 (1984) introduced the <EM>terminfo</EM> feature.   Its  programming  manual
       mentioned the following low-level functions.

       <STRONG>Function</STRONG>    <STRONG>Description</STRONG>
       ------------------------------------------------------------------------
       <STRONG>fixterm</STRONG>     restore terminal to "in <EM>curses</EM>" state
       <STRONG>gettmode</STRONG>    establish current terminal modes
       <STRONG>mvcur</STRONG>       low level cursor motion
       <STRONG>putp</STRONG>        use <STRONG>tputs</STRONG> to send characters via <EM>putchar</EM>
       <STRONG>resetterm</STRONG>   set terminal modes to "out of <EM>curses</EM>" state

       <STRONG>resetty</STRONG>     reset terminal flags to stored value
       <STRONG>saveterm</STRONG>    save current modes as "in <EM>curses</EM>" state
       <STRONG>savetty</STRONG>     store current terminal flags
       <STRONG>setterm</STRONG>     establish terminal with given type
       <STRONG>setupterm</STRONG>   establish terminal with given type
       <STRONG>tparm</STRONG>       interpolate parameters into string capability
       <STRONG>tputs</STRONG>       apply padding information to a string
       <STRONG>vidattr</STRONG>     like <STRONG>vidputs</STRONG>, but output through <EM>putchar</EM>
       <STRONG>vidputs</STRONG>     write string to terminal, applying specified attributes

       The  programming  manual  also mentioned functions provided for <EM>termcap</EM>
       compatibility (commenting that they "may go away at a later date").

       <STRONG>Function</STRONG>   <STRONG>Description</STRONG>
       ------------------------------------------------------------------------
       <STRONG>tgetent</STRONG>    look up <EM>termcap</EM> entry for given <EM>name</EM>
       <STRONG>tgetflag</STRONG>   get Boolean entry for given <EM>id</EM>
       <STRONG>tgetnum</STRONG>    get numeric entry for given <EM>id</EM>
       <STRONG>tgetstr</STRONG>    get string entry for given <EM>id</EM>
       <STRONG>tgoto</STRONG>      apply parameters to given capability
       <STRONG>tputs</STRONG>      write characters via a function parameter, applying padding

       Early <EM>terminfo</EM> programs obtained capability values  from  the  <EM>TERMINAL</EM>
       structure initialized by <STRONG>setupterm</STRONG>.

       SVr3   (1987)   extended  <EM>terminfo</EM>  by  adding  functions  to  retrieve
       capability values (like the <EM>termcap</EM> interface), and reusing  <STRONG>tgoto</STRONG>  and
       <STRONG>tputs</STRONG>.

       <STRONG>Function</STRONG>    <STRONG>Description</STRONG>
       ------------------------------------------------------------------------
       <STRONG>tigetflag</STRONG>   get Boolean entry for given <EM>id</EM>
       <STRONG>tigetnum</STRONG>    get numeric entry for given <EM>id</EM>
       <STRONG>tigetstr</STRONG>    get string entry for given <EM>id</EM>

       SVr3  also  replaced several of the SVr2 <EM>terminfo</EM> functions that had no
       counterpart in the <EM>termcap</EM> interface, documenting them as obsolete.

       <STRONG>Function</STRONG>    <STRONG>Replaced</STRONG> <STRONG>by</STRONG>
       ------------------------------------------------------------------------
       crmode      cbreak
       fixterm     reset_prog_mode
       gettmode    <EM>n/a</EM>
       nocrmode    nocbreak
       resetterm   reset_shell_mode
       saveterm    def_prog_mode
       setterm     setupterm

       SVr3 kept the <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG>, and <STRONG>vidputs</STRONG> functions, along  with  <STRONG>putp</STRONG>,
       <STRONG>tparm</STRONG>,  and  <STRONG>tputs</STRONG>.   The latter were needed to support padding, and to
       handle capabilities accessed by functions such as <STRONG>vidattr</STRONG>  (which  used
       more than the two parameters supported by <STRONG>tgoto</STRONG>).

       SVr3   introduced   the   functions   for  switching  between  terminal
       descriptions;  for  example,  <STRONG>set_curterm</STRONG>.   Some   changes   reflected
       incremental improvements to the SVr2 library.

       <STRONG>o</STRONG>   The  <EM>TERMINAL</EM>  type  definition  was introduced in SVr3.01, for the
           <EM>term</EM> structure provided in SVr2.

       <STRONG>o</STRONG>   Various global variables such as <STRONG>boolnames</STRONG> were  mentioned  in  the
           programming  manual  at  this  point, though the variables had been
           provided in SVr2.

       SVr4 (1989) added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions.

       Other low-level functions are declared in the <EM>curses</EM>  header  files  of
       Unix  systems,  but  none are documented.  Those noted as "obsolete" by
       SVr3 remained in use by System V's <STRONG>vi(1)</STRONG> editor.


</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
       <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>,   <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>,   <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>,   <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>,
       <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>,   <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>,   <STRONG>putc(3)</STRONG>,  <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>,
       <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>



ncurses 6.5                       2024-04-13                 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>
</PRE>
<div class="nav">
<ul>
<li><a href="#h2-NAME">NAME</a></li>
<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
<ul>
<li><a href="#h3-Initialization">Initialization</a></li>
<li><a href="#h3-The-Terminal-State">The Terminal State</a></li>
<li><a href="#h3-Formatting-Output">Formatting Output</a></li>
<li><a href="#h3-Output-Functions">Output Functions</a></li>
<li><a href="#h3-Terminal-Capability-Functions">Terminal Capability Functions</a></li>
<li><a href="#h3-Terminal-Capability-Names">Terminal Capability Names</a></li>
<li><a href="#h3-Releasing-Memory">Releasing Memory</a></li>
</ul>
</li>
<li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
<li><a href="#h2-NOTES">NOTES</a></li>
<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li>
<li><a href="#h2-PORTABILITY">PORTABILITY</a>
<ul>
<li><a href="#h3-Compatibility-Macros">Compatibility Macros</a></li>
<li><a href="#h3-Legacy-Data">Legacy Data</a></li>
<li><a href="#h3-Output-Buffering">Output Buffering</a></li>
<li><a href="#h3-Function-Prototypes">Function Prototypes</a></li>
<li><a href="#h3-Other-Portability-Issues">Other Portability Issues</a></li>
</ul>
</li>
<li><a href="#h2-HISTORY">HISTORY</a></li>
<li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
</ul>
</div>
</BODY>
</HTML>
